test(ltx-2.5): the register boundary, made numerically reachable (#435) - #597

FOLLOWING_AGENTS_PROTOCOL

A fresh review of the L9c connector PR passed the change and found a hole in its
gate. `prompt_embeds_valid_rows` is the single knob deciding which token
positions become the connector's TRAINED `learnable_registers` and which carry
caller-supplied conditioning -- on the accepted render, 104 of 128 rows are
registers. The reviewer changed `s = im.prompt_valid_rows` to
`s = im.prompt_valid_rows + 1` at `ltx2_video.cpp:744` and `test_ltx2_video`
stayed fully green: 23/23 cases, 253/253 assertions, exit 0. Reproduced here
before anything was written.

WHY THE COVERAGE COULD NOT SEE IT. The only case on that knob asserted that a
render at valid=4 differs from one at valid=2. ANY monotone corruption of the
boundary keeps that true, so the whole family passes it. The defect it cannot
see is ONE padded row conditioned on caller junk instead of a trained register:
finite, correctly shaped, plausible, and wrong.

WHAT MAKES THE BOUNDARY REACHABLE IS THE SUBSTITUTION, NOT THE MASK.
`binary_mask * hidden_states + (1 - binary_mask) * registers`
(embeddings_connector.py:148-150) REPLACES a masked position's features, so what
the caller supplied there cannot reach the render at all. The mask carries
nothing: with registers on, :152 returns `torch.zeros_like(mask)`, and
`_to_binary_mask`'s `encoded_mask < 0.000001` (embeddings_processor.py:46-48) is
satisfied by BOTH values an additive mask holds, so what the DiT receives is all
ones either way.

Positions therefore separate by whether perturbing them moves a byte, and the
boundary is pinned from BOTH sides:

  rows [valid, N) are REGISTERS -> perturbing them must change NOTHING
  rows [0, valid)  are CAPTION  -> perturbing the last one must change something

The polarity is `(attention_mask - 1) * finfo.max`
(transformer_args.py:203-206) and the contiguity is `_compute_right_pad_order`'s
stable descending argsort (embeddings_processor.py:33-38), which is what makes
the padded set the suffix `[valid, N)` that the extra names.

RED FIRST, on the product code, restored byte-for-byte after each run
(`git diff` empty, HEAD unchanged, verified per mutation):

  + 1      "every row at or past the count is a register" FAILS   110/111
  - 1      "the row just BEFORE the count is caption"     FAILS   110/111
  0        both caption arms                              FAIL    109/111
  v_rows   "every row at or past the count is a register" FAILS   110/111

and `+ 1` over the WHOLE suite: 24 cases, 23 passed, 1 failed; 364 assertions,
363 passed, 1 failed. Only the new case moves, which is the finding reproduced
and closed in one run.

TWO SIBLING FINDINGS FOLDED IN.

F3 is a correction of a claim, and then a gate under it. The L9c commit message
said `Ltx2ParseConnectorConfig` "mirrors both configurators key for key". It
does not: `connector_num_learnable_registers` is read here and by NEITHER
configurator (embeddings_connector.py:194-219 and :222-256 both take the class
default of 128). The divergence is deliberate and stays -- a checkpoint
declaring something else must not be silently run at 128 -- but a read nothing
can falsify is a claim rather than a gate, so it now has one: the fixture's
stored table stays `[2, dim]` while the config declares 4, and
`Ltx2LoadConnectorWeights`' shape check fires. REDs when the read is made inert.

The correction itself lands in `porting-inventory.md` and in the test, NOT as a
comment beside the parse. `check-doc-checkpoint` classifies any path under
`src/vllm/model_executor/models/` as `feature_surface` and would demand a
`docs/FEATURES.md` entry for a comment that changes no feature -- and inventing
one to satisfy a checker is a false record. The parse's existing comment already
says "NOT read by either configurator", so nothing there was untrue; what was
missing was the gate, and the gate is what this adds.

F4 is an unreachable branch that named the wrong reason. The refusal on a masked
cross-attention mask said it fires "when the connector runs with
num_learnable_registers = 0". It cannot: with registers disabled the caller's
additive mask passes straight through and `< 0.000001` is still true at every
position, so the branch is unreachable on every input either reference produces.
The comment and the message now say that, name what WOULD reach it, and say why
it is not gated.

Also in the record: `porting-inventory.md` cited "mutation M3/M4" by labels that
existed only in a PR body, which git cannot resolve -- replaced with the test
case names, which are in the tree.

NOT REPRODUCED, and recorded rather than dropped: the shipped-checkpoint case
does not skip silently. `MESSAGE: SKIPPED: set LTX2_CHECKPOINT_ROOT ...` prints
in the binary's own output, in the baseline run above. It IS invisible under
`ctest`, which captures a passing test's output, and its env is deliberately not
the tree-wide `CHECKPOINT_ROOT` -- `.env.example` says that one "declares an
INTENT, not a behaviour" and nothing reads it. Both are now stated at the case
so a green ctest row cannot be read as "the shipped checkpoints were read".

Gate: clean-configured CPU-only Release build, BUILD_EXIT=0, no
`No space left`/`BFD assertion`/kill in the log, `ctest -N` 399 tests.

Issue: #435

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: AGENT:claude-opus-5 [Claude Code]